Night Owl 6/Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso/022a/dta16.zip/DTA.DOC

Text File | 1992-01-25 | 15KB | 361 lines

DTA (Dave's .TGA Animation Program)
Copyright (c) 1991, by David K. Mason

Release 1.6 (01/25/91)

DTA is a command-line utility designed to post-process TGA
files created by the DKB/Starlite/PV/POV and POLYRAY ray-tracers,
.IMG files from the Vivid ray-tracer, or .GIF files
(87a variety only).

DTA can:

 o Create a single optimal 256-color palette from a series of
   truecolor pictures, and then create an Autodesk Animator .FLI
   file out of them.
 o Or, just save the palette as a .COL file (readable by either
   Autodesk Animator or TGAFLI).
 o Or, save the palette as a .MAP file (readable by PICLAB and
   FRACTINT).
 o Or, read in a palette file in either .COL or .MAP format
   and animate a bunch of pictures using that palette.
 o Or, animate a bunch of pictures using grayscale.
 o Or, convert pictures to .GIF files.

Syntax:

 Type DTA with no parameters to see a listing of parameters
 and stuff.

NOTE:
 There was some other stuff I'd planned to put into this
 release of DTA, like color-mapped TGA support, compressed
 TGA output, etc.  But I've gotten distracted by another
 project, so I'm going to let DTA sit for a while.
 Keep the suggestions and bug reports comin', though
 'cause I will get back to it eventually.

What's new:

 Rel 1.6 (01/25/91)
  o Can write uncompressed Targa-16 files (use the /B16 switch).
  o Can read compressed and uncompressed Targa-16 files (like
    those you can produce with POLYRAY).
  o Added /M option, which causes the palette tree-reduction
    routine to prune the most popular branches instead of
    least popular.  The resulting palette should be biased
    a bit more toward detail in a picture instead of smoothly
    shaded areas.
  o Added /L option, which allows you to set the initial
    (pre-reduction, that is) color resolution for one or
    more of the color components (r,g,b) to something other
    than the default 6 bits.  It doesn't make sense to set
    it higher than 6 bits, since that's the most VGA can display.
    But you could, for example, tell DTA to use fewer bits for
    green and blue so that the reds get more representation,
    like so:
     dta *.tga /lb2 /lg3
    (that sets the blue resolution to 2 bits and the green
    resolution to 3 bits).
  o When averaging pictures, DTA used to use an equal percentage
    of each of the original pictures.  That's still the default,
    but with the /E option, you can change this.  /E lets you
    specify two numbers: (a) the amount of weight to give the
    first picture, and (b) how much to increment that weight
    for each successive picture.  So, assuming you start with
    three TGA files, if you use this command:
     dta *.tga /a5 /e2;1 /fg
    the first frame will get a weight of 2, the second will get
    3, and the third will get 4.  Which means the resulting
    GIF file will be made up 22% from the first picture, 33%
    from the second, 44% from the third.
    This can be used with /t (trail) as well as /a (average).
    The increment number can be negative... if you want
    the first picture to stand out more than the others.
    The default for the initial weight is 1.  The default
    for the increment is 0.  If you use /e without specifying
    an increment, then the increment is set to 1.
    If you don't specify either number, then both numbers are
    set to 1.
  o Fixed a bug in averaging GIF files.
  o When creating a new TGA file, DTA forgot to use the resolution
    of the input file like it does with GIF files.  Fixed.
  o Can now ignore comments in TGA files properly.
  o When creating GIF files, DTA now saves at the same
    time it performs the mapping step, instead of saving to
    a buffer and saving it at the end.
    For pictures that would require virtual memory (bigger
    than 320x200), this'll save some time.
  o Added 640x400 resolution for low-end SVGA.
 Rel 1.5f (12/13/91)
  o DTA can now read IMG files created by the Stephen Coy's
    Vivid raytracer.
  o Speeded up some input functions that were slowed down
    because of some recently added features.
  o Another probably unsuccessful attempt to fix the same bug
    that 1.5d was supposed to fix.
  o Fixed a bug in dithering (sometimes DTA wouldn't dither
    the whole picture).
  o DTA wasn't deleting a temporary file that it sometimes
    creates.  Now it does.
 Rel 1.5e (11/24/91)
  o DTA can now read GIF files as well as TGAs.  GIF87 only,
    no interlacing allowed.
  o Added a /V (verbose) command line option.  If you
    specify this, DTA will tell you exactly how many
    bytes each frame in an animation take up.
  o Added the /W option, which forces DTA to use the
    SVGA-type compression method, even if generating
    a 320x200 .FLI.
  o By the way the fix in 1.5d didn't help.  However, the
    problem is pretty rare.  Maybe next time.
 Rel 1.5d (11/18/91)
  o Hopefully fixed a bug that caused problems with Trilobyte's
    PLAY program.
 Rel 1.5c (11/11/91)
  o Attempting to support 800x600, 1024x768, and 1280x1024
    SVGA resolutions.  Note: This is completely untested.
    I haven't the foggiest idea if it works or not.
 Rel 1.5b (11/09/91)
  o Added "expansion" feature, which inserts averaged frames
    between regular frames.
  o Fixed some bugs in some weird combinations of 3d, "pingpong",
    and "trail".
 Rel 1.5 (11/05/91)
  o Ordered dithering
  o VGA "mode x" .FLI resolutions
  o fixed a bug in 320x200 delta encoding
    which would sometimes cause animations to crash
  o "averaging" and "trailing" (where individual frames are
    created by averaging the colors across multiple input
    files).  The difference between "averaging" and "trailing" is:
     If you run an "average" of 2 on 10 .TGAs, frame 1 will be
    an average of files 1 and 2, frame 2 an average of files 3
    and 4, and so on.
     If you do a "trail" of 2 on 10 .TGAs,
    then frame 1 will be an average of 1 and 2, frame 2 an average
    of files 2 and 3, frame 3 an average of files 3 and 4, and
    so on.
  o Red/blue-type 3d
  o TGA output (pretty useless unless you're also averaging
    input files or creating 3d images).  DTA does not compress
    TGAs just yet.
 Rel 1.4 TEST 2 (10/12/91)
  o DTA can now read compressed .TGAs.
  o DTA can new create .GIFs or .PCXs.
  o Before 1.4, DTA would give up on compressing a frame if the
    compressed version required more than about 64K to store.
    This was fine for 320x200 animations, where an uncompressed
    frame only requires 64K anyway, but it left something to
    be desired for 640x480 animations, where an uncompressed
    frame takes up about 300K.
    Now, 640x480 frames will be compressed unless the compressed
    version takes up more than about 300K.
 Rel 1.3c (09/14/31) (second bug fix)
  o .MAP files were missing carriage returns between
    lines.
 Rel 1.3b (09/13/31) (bugfix release)
  o Fixed bugs from the disastrous Rel. 1.3
    (including 640x480 .FLIs)
  o Big speed increase in palette creation
 Rel 1.3 (09/03/91)
  o 640x480 .FLIs
  o Better .FLI compression.
  o In pre-1.3, the animation was stored in a temporary file,
    then at the end a new file was created with the .FLI header,
    and then the temporary file was copied onto the end of that.
    Now, only one file is used to store the animation, and the
    header gets modified at the end of the process.
  o Frame #1 is now stored in a temporary file so that it doesn't
    need to be recreated for the "ring frame".
  o Added /G32 option for creating 32-level grayscale animations
    for laptops.
  o Fixed some bugs.
 Rel 1.2 (08/06/91)
  o Added support for exit codes returned by LHA 2.13...
    If LHA returns a non-zero exit code, DTA will abort.
  o If you hit the escape key while DTA is running,
    DTA will abort as soon as it's done processing
    an input file.
  o Changed the way input files are sorted... see
    Examples, below.
  o Added /p (pingpong) option.  (makes animation go in
    0-1-2-3-4-3-2-1-0 order instead of 0-1-2-3-4-0).
  o Added support for lists of files to process.
    Tell DTA that a file is a list by preceding the filename
    by an "@" character.  A list file may contain
    the names of .TGA files or .LZH files.  You can't put
    the name of another list file in a list file.
  o Will now clip .TGA files with a resolution greater than
    320x200 instead of choking on them.
  o Added /O (sort order) option.  When DTA has to sort filenames,
    like when you use a wildcards or when you just give the name
    of an .LZH file, "/O+" (the default) will tell DTA to sort
    in ascending order, "/O-" in descending order.
    This option is positional... it will only affect files
    specified AFTER the option on the DTA command line.
    You can use this more than once on a DTA command line.
 Rel 1.1 (07/15/91)
  o Can now extract .TGA files from inside of .LZH files.
    (by shelling to LHA.EXE)  Takes longer, but can save plenty
    of disk space.
  o Added /s (to specify playing speed).
  o Doesn't choke on truncated .TGA files any more.
  o Rewrote some I/O routines so scanning palettes is quicker.

Examples:

  C>dta rocket*.tga /fcrocket
    make a palette for all tga files starting with "rocket" and put
    the palette in an Animator palette file called "ROCKET.COL".

  C>dta pic1 pic2 pic3 /fmxxx
    make a palette for targa files "PIC1.TGA", "PIC2.TGA", and "PIC3.TGA", and
    save the palette into a PICLAB palette file called "ROCKET.MAP".

  C>dta rocket* /frocket /df
    turn all tga files beginning with "rocket" into an animation file called
    "ROCKET.FLI", and dither the frames.

  C>dta rocket* /g /do2 /p
    turn all tga files beginning with "rocket" into a grayscale
    animation.  Dither it (using ordered dither strength 2).
    Ping-pong it.

  C>dta garbage
    make an animation for one targa file called "GARBAGE.TGA", and save it
    as "ANIM.FLI".  Don't dither.

  C>dta @wing2.lst /s10 /fwing2.fli
    make an animation from the targa files listed in a text file
    called "wing2.lst".  Make the speed "10", and put the output
    in a file called "wing2.fli".

  C>dta bbb*.tga aaa*.tga /upal1.col /upal2.map /ffred
    create an animation using all tga files whose name begins with
    "BBB", and "AAA".  Note that unlike the previous version of DTA,
    The "BBB" files WILL appear in the animation before the "AAA"
    files.  The "BBB" files will be sorted alphabetically,
    and so will the "AAA" files, but separately.
    For the palette of the animation, read in an Animator palette file
    called "PAL1.COL", and merge it with a Piclab palette file called
    "PAL2.MAP".  Put the animation in a file called "FRED.FLI".

  C>dta /o- xxx*.tga /o+ zzz.lzh /g /s5 /p
    Make a .FLI with all .TGAs whose filename begins with
    XXX (sorting the filenames backwards), then all .TGAs
    residing in ZZZ.LZH (sorting the filenames forwards).
    The .FLI should be in grayscale, at speed 5.
    And pingpong the whole thing.

  C>dta *.tga /gif
    Make .GIFs from all .TGAs in the current directory.

  C>dta sombrero /fp /d /g
    Make a dithered grayscale .PCX from a file called
    SOMBRERO.TGA

  C>dta left*.tga rght*.tga /3d
    Make a red/blue 3d .FLI file, using the .TGA files beginning
    with "left" as the red component, and the ones beginning with
    "rght" as the blue component.  For this to work right, there
    must be an equal number of "left" and "rght" .TGAs.

  C>dta xxx* /ftyy /aa
    Average all .TGAs beginning with the string "xxx", and create
    a new file called "yy.tga".  (Note: averaging will work with
    up to 10 files, but no more.)

  C>dta xxx*.tga /t3 /do3 /ffzzz
    Create a file called zzz.fli.  Assuming there are 5 .TGA files
    beginning with the string "xxx", frame 1 of the animation will
    be an average of files 1,2, and 3; frame 2 will be an average
    of files 2,3, and 4; ... frame 5 will be an average of
    files 5,1, and 2.

  C>dta xxx*.tga /x3
    Create a file called anim.fli. Assuming again that there are
    5 .TGA files beginning with the string "xxx", it'll be a
    15-frame animation where frame 1 is derived from the first
    .TGA file, frame 2 will be be a be a 67%/33% mix of files
    1 and 2, frame 3 a 33%/67% mix of the same files, frame 4
    just file 2, and so on.

  C>dta *.gif
    Creates a file called anim.fli from a bunch of .GIF files.

Speed:

  DTA is fastest when you use grayscale instead of a palette.
  even if you dither.

  If you let DTA generate its own palette, DTA is still
  relatively speedy.  It gets (lots) slower if you dither.

  If you create an animation from .TGA files stored in an .LZH
  file, then DTA is REAL slow.

  If you're creating a 640x480 .FLI, then DTA requires about 614K
  of memory just to store the pictures that it's comparing.
  Since PCs just don't have that kind of memory lying around,
  DTA will put it in EMS (expanded memory) if you have it, or
  virtual memory (paging to disk) if you don't.  EMS is LOTS
  faster than virtual memory.

  If you average multiple files, that's going to slow things down.

Credits:

  To create palettes and select colors from palettes, this
  program uses an algorithm that I found in an article called "A
  Simple Method for Color Quantization:  Octree Quantization," by
  Michael Gervautz and Werner Purgathofer, which can be found in
  a book called "Graphics Gems," edited by Andrew S. Glassner.  I
  recommend this book highly.

  The .FLI file format was explained in a document called
  FLIDOC.TXT from Jim Kent's FLILIB.  I wasn't able to use this C
  library in DTA, since I do my coding in Turbo Pascal, but the
  document contained all the info I needed.  (Jim Kent is also
  the guy who, with Tom Hudson, wrote TGAFLI, and who developed
  Animator and Animator Pro.)

  More thanks to Jim Kent for his info about 640x480 .FLIs on
  BIX.

  The ram/ems/virtual memory system in DTA is a modified
  version of the large array object (OPLARRAY) from TurboPower
  Software's object library for Turbo Pascal, Object Professional.
  (OPRO is a MUST for TP programmers, and I hear a C++ version
  has been or will soon be released.)

  Thanks to Dan Farmer, Alexander Enzmann, Jeff Bowermaster,
  and others for their excellent suggestions.

  Thanks to the Cafe Algiers in Harvard Square for being such
  a cool place to swill arabic coffee and discuss ray-tracing
  and animation.

Money matters:

  If you think this program is worth it, send me some cash or
  some beer or something.  If not, I'll survive.

Disclaimer:

  If you use DTA, you do so at your own risk.  I won't be held
  responsible if it screws anything up.

Support:

  If you've got any requests/bug reports/suggestions, send a message
  to:
    "David Mason" on the "You Can Call Me Ray" BBS, [phone]
    and on "Channel 1" BBS, [phone]

  You'll probably get some kind of a response.

-- David K. Mason
   P.O. Box 181015
   Boston, MA 02118